Verify each finding against the current code and only fix it if needed.

Inline comments:
In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/application/AudioAnalysisUseCase.java`:
- Around line 68-72: The catch block in AudioAnalysisUseCase uses e.getMessage()
which can be null; create a non-null error string (e.g., String errorMsg =
e.getMessage() != null ? e.getMessage() : e.toString()) and use that variable in
the log.error call, in updateStatus(bucket, entityId,
AudioProcessingStatus.FAILED, errorMsg), and when constructing the
RuntimeException to ensure diagnostic information is preserved; update the catch
block around the existing log.error/updateStatus/throw to reference this
errorMsg instead of directly calling e.getMessage().
- Line 107: The call to debugVisualizer.generateHeatmap(result, "debug_" +
submissionId + ".png") in AudioAnalysisUseCase can throw after
resultRepository.save(...) and cause the submission to be marked FAILED; wrap
the heatmap generation in a try-catch so any exception is caught and logged
(e.g., via the class logger) and not rethrown, ensuring the saved analysis
result and submission status are not changed by heatmap failures; keep
resultRepository.save(...) as the canonical success path and make heatmap
generation non-fatal (or run it asynchronously) so failures only produce a log
entry.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/domain/port/ReferenceRepository.java`:
- Around line 25-27: Change the port API so findById returns
Optional<FeatureSequence> instead of possibly-null FeatureSequence and
standardize the UUID parameter name to assignmentId to make the intent explicit;
update the method signature of findById(UUID assignmentId) ->
Optional<FeatureSequence> findById(UUID assignmentId) and rename the UUID
parameter in updateStatus(UUID id, AudioProcessingStatus status, String
errorMessage) to updateStatus(UUID assignmentId, AudioProcessingStatus status,
String errorMessage), and then update all implementations and callers to handle
Optional properly and to use assignmentId consistently.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/domain/port/ResultRepository.java`:
- Around line 12-14: Change the lookup contract on ResultRepository: make
findAssignmentIdBySubmissionId return Optional<UUID> instead of possibly-null
UUID (so callers must explicitly handle empty) and update all implementations
and call-sites accordingly; also clarify the updateStatus parameter name from
generic id to a clear identifier (e.g., resultId or assignmentId) in the
ResultRepository.updateStatus signature and propagate that rename to
implementations and usages to avoid ID ambiguity.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/persistence/adapter/SubmissionPersistenceAdapter.java`:
- Around line 37-43: Add a read-only transaction annotation to the
findAssignmentIdBySubmissionId method in SubmissionPersistenceAdapter: annotate
the method (or class if preferred) with `@Transactional`(readOnly = true) so the
repository.findById(...) read operation can benefit from DB-level optimizations
and the intent is explicit; ensure the import for
org.springframework.transaction.annotation.Transactional is present and apply it
to the method containing findAssignmentIdBySubmissionId.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/persistence/entity/AssignmentEntity.java`:
- Around line 10-29: Add a versioned DB migration that creates/updates the
assignments table to match AssignmentEntity: add the reference_spectre_cache
column (binary) and error_message column (text/varchar) and, if the table itself
is new in this PR, include full CREATE TABLE for assignments with id (UUID) and
status (string) columns; implement this as a Flyway (V###__describe.sql) or
Liquibase changeSet to ensure deterministic rollout rather than relying on
ddl-auto. Locate the schema differences by inspecting AssignmentEntity and
create an idempotent SQL migration that ALTERs the existing assignments table to
add reference_spectre_cache (bytea/BLOB) and error_message (text) and a
migration entry in your migrations folder so CI/production runs the versioned
migration during deployment.
- Around line 24-28: The errorMessage field in AssignmentEntity is currently
mapped with `@Column` and will default to varchar(255); update the `@Column`
annotation on the errorMessage field to set columnDefinition = "text" (i.e.,
`@Column`(name = "error_message", columnDefinition = "text")) so the database
column can store longer error texts without truncation; locate the errorMessage
field in the AssignmentEntity class and modify its `@Column` accordingly.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/persistence/entity/SubmissionEntity.java`:
- Around line 23-30: SubmissionEntity's required fields (id, assignmentId,
status) lack nullability constraints which can permit invalid rows; update the
JPA annotations on the UUID id, assignmentId and the AudioProcessingStatus
status in class SubmissionEntity to declare non-nullable columns (e.g., add
`@Column`(nullable = false) to assignmentId and status and ensure the id column is
marked non-nullable via `@Column`(nullable = false) or the existing `@Id` mapping),
then run or add the corresponding schema migration to enforce NOT NULL at the
database level.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/persistence/repository/JpaAssignmentRepository.java`:
- Around line 14-15: Update the repository update methods to use explicit
parameter binding and return the update count: in JpaAssignmentRepository change
the updateStatus method to annotate its parameters with `@Param`("id"),
`@Param`("status") and `@Param`("error") and change the return type from void to int
so the method returns the number of rows updated; apply the identical edits to
the corresponding method in JpaSubmissionRepository (add `@Param` annotations with
the same names used in the JPQL and change the return type to int) so
missing-row updates can be detected at runtime.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/utils/FeatureBinarySerializer.java`:
- Around line 50-56: The overflow check in FeatureBinarySerializer currently
computes totalElements and checks totalElements * Float.BYTES against
Integer.MAX_VALUE but omits HEADER_SIZE; update the guard to compute
requiredBytes = HEADER_SIZE + (long)frameCount * binCount * Float.BYTES (use a
long) and compare requiredBytes against Integer.MAX_VALUE before casting to int,
then set totalBytes = (int) requiredBytes; apply the same change to the
analogous check around lines 94-100 so both places include HEADER_SIZE and use
long arithmetic to prevent overflow.
- Around line 28-29: The JavaDoc in FeatureBinarySerializer currently documents
`@throws` IllegalArgumentException for null frames but the implementation throws
NullPointerException; update the JavaDoc to match the code by replacing the
`@throws` IllegalArgumentException clause with `@throws` NullPointerException (or
alternately change the method implementation to throw IllegalArgumentException
consistently), ensuring the javadoc for the method in FeatureBinarySerializer
that describes the frames parameter reflects the actual exception type thrown.

In
`@backend/smartjam-analyzer/src/test/java/com/smartjam/smartjamanalyzer/application/AudioAnalysisUseCaseTest.java`:
- Around line 58-83: Add a new test that covers the "submissions" flow (e.g.,
shouldProcessStudentSubmission) because shouldProcessInOrder only covers
"references"; in that test mock workspaceFactory.create(),
storage.downloadAudioFile(...), converter.convertToStandardWav(...),
featureExtractor.extract(...) to return student Features, mock
resultRepository.findAssignmentIdBySubmissionId(VALID_UUID) to return an
assignmentId and referenceRepository.findById(assignmentId) to return teacher
Features, mock performanceEvaluator.evaluate(teacherFeatures, studentFeatures)
to return an AnalysisResult, run useCase.execute(bucket, fileKey) with
bucket="submissions", then verify resultRepository.updateStatus(VALID_UUID,
AudioProcessingStatus.ANALYZING, null), resultRepository.save(VALID_UUID,
mockResult), and debugVisualizer.generateHeatmap(eq(mockResult),
contains("debug_")) to ensure the submission path invokes
findAssignmentIdBySubmissionId, findById, evaluate and generateHeatmap.

In
`@backend/smartjam-analyzer/src/test/java/com/smartjam/smartjamanalyzer/infrastructure/converter/FfmpegAudioConverterTest.java`:
- Line 20: Convert the inline TODO in FfmpegAudioConverterTest into a tracked
backlog item and/or an explicit pending test: create a ticket in your issue
tracker describing the missing "filter passthrough" test and reference that
ticket ID in the test comment, or mark the test as pending/disabled (e.g., with
JUnit's `@Disabled`) and include the ticket ID and a short description; ensure the
TODO text in the FfmpegAudioConverterTest class is replaced with the ticket
reference and a one-line note that the filter propagation test will be
implemented against the ticket so it won't be silently forgotten.

In
`@backend/smartjam-analyzer/src/test/java/com/smartjam/smartjamanalyzer/infrastructure/utils/FeatureBinarySerializerTest.java`:
- Around line 50-55: The test method deserializeTooShortReturnsEmpty currently
asserts that FeatureBinarySerializer.deserialize(shortData) returns null, but
its `@DisplayName` says "returns empty list"; update the `@DisplayName` to match the
assertion (e.g., "Десериализация слишком короткого массива возвращает null") so
the description aligns with the actual assertion and intent of the test.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/application/AudioAnalysisUseCase.java`:
- Around line 30-38: In execute (AudioAnalysisUseCase.execute) validate the
incoming bucket string up front against the allowed set ("references",
"submissions"); if it's not one of those, log/mark an error and return before
creating a Workspace or calling updateStatus so we never set ANALYZING for
unknown buckets. Ensure the subsequent updateStatus(...) and downstream saves
only follow the same two-value contract (use referenceRepository for
"references" and resultRepository for "submissions") and do not attempt any save
or status transitions for invalid buckets.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/domain/port/ReferenceRepository.java`:
- Around line 20-35: Update the JavaDoc on the ReferenceRepository port to match
the API: for findFeaturesById(UUID assignmentId) state that it returns an
Optional<FeatureSequence> which will be empty if no features are found (do not
mention null), and clarify that the parameter assignmentId refers to the
assignment's unique identifier (not a submission); for updateStatus(UUID
assignmentId, AudioProcessingStatus status, String errorMessage) correct the
param text to say assignmentId is the assignment identifier and keep
errorMessage as optional failure description; ensure the return and param
descriptions reference FeatureSequence, Optional, findFeaturesById,
updateStatus, AudioProcessingStatus, and assignmentId consistently.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/persistence/entity/SubmissionEntity.java`:
- Around line 45-46: The errorMessage field in SubmissionEntity should use the
same TEXT column definition as AssignmentEntity to avoid VARCHAR truncation;
update the `@Column` annotation on the errorMessage field in SubmissionEntity (the
private String errorMessage) to include columnDefinition = "TEXT" (e.g.,
`@Column`(name = "error_message", columnDefinition = "TEXT") ) so long
FFmpeg/extractor messages are not truncated.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/persistence/repository/JpaSubmissionRepository.java`:
- Around line 24-26: Update JpaSubmissionRepository.updateStatus to return an
int and use explicit `@Param` bindings: annotate the method parameters with
`@Param`("id"), `@Param`("status") and `@Param`("error") so the named parameters in
the JPQL ("UPDATE SubmissionEntity s SET s.status = :status, s.errorMessage =
:error WHERE s.id = :id") are unambiguous, and change the return type from void
to int so callers can check the number of rows affected (0 means no update).
Keep the `@Modifying` annotation and ensure parameter names exactly match the JPQL
names (status, error, id) and the AudioProcessingStatus type for the status
parameter.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/utils/FeatureBinarySerializer.java`:
- Around line 29-37: Update the JavaDoc for FeatureBinarySerializer.serialize to
match the implementation: state that if the sequence has no frames the method
returns an empty byte[] (instead of throwing IllegalArgumentException); keep the
documented IllegalArgumentException conditions for null sequence
(Objects.requireNonNull) and for frames with differing lengths if that check
exists elsewhere, and reference FeatureSequence.frames() in the doc so callers
know empty-frame input yields an empty byte[] result.

---

Duplicate comments:
In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/application/AudioAnalysisUseCase.java`:
- Around line 68-75: In AudioAnalysisUseCase's catch block, you normalize the
exception message into the local variable errorMsg but then pass e.getMessage()
to updateStatus; change the updateStatus call to pass errorMsg (not
e.getMessage()) so FAILED records persist the normalized message (reference:
errorMsg variable, updateStatus method, catch(Exception e) in
AudioAnalysisUseCase).

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/domain/port/ResultRepository.java`:
- Around line 22-29: The method ResultRepository.findAssignmentIdBySubmissionId
currently returns UUID and relies on throwing at runtime to signal "not found";
change its signature to return java.util.Optional<UUID> (i.e., Optional<UUID>
findAssignmentIdBySubmissionId(UUID submissionId)), update the Javadoc to
describe Optional usage instead of throwing, and adjust all implementing classes
and callers to handle Optional.empty() instead of catching an exception so the
absence case is explicit.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/persistence/repository/JpaAssignmentRepository.java`:
- Around line 17-19: The JPQL update method updateStatus in
JpaAssignmentRepository uses named parameters without `@Param` bindings and
returns void, hiding whether rows were affected; change the method signature to
return int and add explicit `@Param` annotations for id, status and error (while
keeping `@Modifying`(clearAutomatically = true) and the existing `@Query`) so Spring
can bind the named parameters correctly and the caller receives the affected-row
count.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/utils/FeatureBinarySerializer.java`:
- Around line 95-101: The current overflow guard in FeatureBinarySerializer
computes totalElements and checks totalElements * Float.BYTES against
Integer.MAX_VALUE but still allows HEADER_SIZE + payload to overflow when
computing expectedBytes; update the check to compute payloadBytes as a long
(payloadBytes = totalElements * (long) Float.BYTES), then verify that
HEADER_SIZE + payloadBytes <= Integer.MAX_VALUE before casting to int, and use
the long sum to set expectedBytes safely (int expectedBytes = (int)(HEADER_SIZE
+ payloadBytes)); ensure you reference the existing variables totalElements,
frameCount, binCount, HEADER_SIZE, payloadBytes and expectedBytes in the fix.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/application/AudioAnalysisUseCase.java`:
- Around line 123-130: The extractUuid method currently fails on prefixed keys
and throws IllegalArgumentException on parse errors; change extractUuid to first
isolate the last path segment (e.g., take substring after the last '/' if
present), then strip the file extension (substring before last '.'), then
attempt UUID.fromString on that raw segment; on failure do NOT throw
IllegalArgumentException—either return Optional<UUID> (or null) or throw a
specific checked/handled exception (e.g., InvalidFileKeyException) so callers
(the surrounding processing flow) can record a persisted failure state in the
database instead of letting the upload be dropped silently; update all call
sites of extractUuid accordingly (or adapt to Optional) so parse failures are
handled and persisted.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/domain/port/ResultRepository.java`:
- Around line 23-30: The JavaDoc for
ResultRepository.findAssignmentIdBySubmissionId(UUID) incorrectly states it
throws and returns a UUID; update the doc to reflect it returns an
Optional<UUID> and does not throw on missing linkage. Specifically, change the
`@return` to indicate "Optional containing the parent assignment UUID if found, or
Optional.empty() if not" and remove the `@throws` tag; note callers like
SubmissionPersistenceAdapter.findAssignmentIdBySubmissionId(...) return
Optional.empty() and AudioAnalysisUseCase performs the orElseThrow.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/utils/FeatureBinarySerializer.java`:
- Around line 51-56: The multiplication computing totalPayloadBytes in
FeatureBinarySerializer (used in serialize and deserialize) can overflow before
the overflow check; replace the raw multiplies with checked multiplications
(e.g., use Math.multiplyExact for frameCount * binCount and then multiplyExact
by Float.BYTES) and catch ArithmeticException to throw an
IllegalArgumentException with the existing message; apply the same
checked-multiply approach to the other payload-size calculations around lines
95-100 so all paths reject oversized matrices before any cast/array allocation
and still include HEADER_SIZE in the final bounds check.
- Around line 35-36: The serializer currently returns new byte[0] for empty
FeatureSequence which deserialize treats as null; instead have
FeatureBinarySerializer.serialize(FeatureSequence) emit a valid header-sized
payload (populate the HEADER_SIZE bytes with the same format used for non-empty
sequences but with frame count = 0) so an empty sequence round-trips, and ensure
deserialize(byte[] payload) continues to interpret a header with frame count 0
as an empty FeatureSequence (not null); update both serialize(...) occurrences
(the empty-case at sequence.frames().isEmpty() and the similar block at lines
~80-83) and reference HEADER_SIZE, serialize, deserialize, and the frame count
field when implementing the fix.

---

Duplicate comments:
In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/application/AudioAnalysisUseCase.java`:
- Around line 30-38: In execute(...) validate the incoming bucket before calling
updateStatus(..., AudioProcessingStatus.ANALYZING, ...): check the bucket value
immediately after extractUuid(fileKey) and return with a proper terminal status
or throw if unsupported so unsupported buckets never fall through to the
catch-all else; then keep the existing updateStatus call only for the two
supported branches handled by handleTeacherReference(...) and
handleStudentSubmission(...). Locate and apply the same upfront bucket
validation logic in the other similar blocks that call updateStatus (the ones
surrounding handleTeacherReference and handleStudentSubmission) so all paths
enforce the two-bucket contract.

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/application/AudioAnalysisUseCase.java`:
- Around line 123-131: The extractUuid method fails on prefixed S3 keys (e.g.,
"folder/uuid.wav") because it only strips extensions and passes "folder/uuid" to
UUID.fromString; update extractUuid to first strip the extension, then extract
the final path segment (substring after the last '/' or '\\' if present) to
isolate the bare UUID before calling UUID.fromString(rawUuidSegment). Keep the
existing try/catch and IllegalArgumentException but ensure the rawUuidSegment is
what you validate so prefixed keys are accepted.
- Around line 30-38: In AudioAnalysisUseCase.execute validate the incoming
bucket immediately after extracting the UUID and before creating the Workspace
or calling updateStatus for ANALYZING: check that bucket equals "references" or
"submissions", and if not call updateStatus(entityId,
AudioProcessingStatus.FAILED, "unknown bucket: " + bucket) (or the project's
error status) and return; this ensures unknown buckets don't leave an entity
stuck in ANALYZING and prevents skipping the proper handlers
(handleTeacherReference/handleStudentSubmission). Use the same updateStatus
helper and UUID from extractUuid so the failure is recorded against the correct
entity.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/domain/port/ReferenceRepository.java`:
- Around line 28-35: The JavaDoc for ReferenceRepository.updateStatus
incorrectly calls assignmentId a "submission" id; update the `@param`
documentation for assignmentId to say it is the assignment identifier (e.g.,
"unique identifier of the assignment") and ensure the other `@param` entries
(status, errorMessage) remain accurate; locate the updateStatus(UUID
assignmentId, AudioProcessingStatus status, String errorMessage) declaration in
ReferenceRepository and correct only the assignmentId description.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/domain/port/ResultRepository.java`:
- Around line 23-30: The JavaDoc for findAssignmentIdBySubmissionId is
inconsistent with its Optional<UUID> return type: update the method description
to state it returns an Optional containing the parent assignment UUID (or
Optional.empty() when none exists), change the `@return` tag to mention
Optional<UUID>, and remove the incorrect `@throws` RuntimeException tag; ensure
the summary sentence and tags reflect the Optional contract for
findAssignmentIdBySubmissionId.

In
`@backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/utils/FeatureBinarySerializer.java`:
- Around line 81-83: The check in FeatureBinarySerializer that returns null when
data.length < HEADER_SIZE hides malformed payloads; change it so only data ==
null returns null and when data != null but shorter than HEADER_SIZE throw a
clear exception (e.g., IllegalArgumentException with a message mentioning
HEADER_SIZE and actual length) inside the same method where the current check
exists so callers can distinguish absent input from corrupted/short payloads.
- Around line 51-53: The payload-size check in FeatureBinarySerializer uses raw
chained multiplication (frameCount * binCount * Float.BYTES) which can overflow
before the guard; replace those chains in both the serialize and deserialize
paths by performing checked multiplications (e.g., use Math.multiplyExact
stepwise or equivalent checked casts) when computing totalPayloadBytes from
frameCount, binCount, and Float.BYTES, then compare the resulting long safely
against Integer.MAX_VALUE - HEADER_SIZE; update both places that reference
frameCount/binCount/Float.BYTES (the totalPayloadBytes calculation around the
serialize method and the similar calculation in the deserialize path) to use the
checked-multiply approach and preserve the existing IllegalArgumentException
behavior if the checked multiplication throws or the final size exceeds the
allowed limit.
- Around line 35-37: Remove the unreachable empty-sequence branch in
FeatureBinarySerializer.serialize(...): delete the if
(sequence.frames().isEmpty()) { return new byte[0]; } branch and instead assume
FeatureSequence enforces non-empty frames; to fail fast if the invariant is ever
violated, replace the silent return with an explicit check that throws (e.g.,
IllegalStateException or Preconditions.checkArgument) or an
Objects.requireNonNull/assert on sequence.frames() before proceeding,
referencing the serialize(...) method and the FeatureSequence compact
constructor invariant so invalid state isn't silently swallowed.